home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C ++ / Applications / Venus 3.5 / Readme < prev    next >
Encoding:
Text File  |  1997-05-02  |  9.0 KB  |  167 lines  |  [TEXT/CWIE]
  1. What:    "virtual" flying through the clouds
  2.  
  3. Hot points:
  4.     - simple virtual reality "thing"
  5.     - can use a user-specified elevation map
  6.     - with the complete source and *lots* of comments/explanations
  7.     - shows off a custom (private) event queue and the flexibility it gives
  8.     - NO QuickDraw3D, all rendering/graphics is done by the code itself
  9.     - includes source for a small class library to handle color Mac windows
  10.       and draw images on off-screen GrafWorlds
  11.       (with a _real_ optimization of the CopyBits performance if found possible)
  12.     - animation NOT through null-events
  13.  
  14. Keywords: voxel 3D rendering, visualization, animation, elevation map, panning
  15.   
  16. Contents:
  17.     Readme            - this file
  18.     Venus v3.5        - the application itself
  19.     Venus.mu        - a project to build it
  20.     Venus.mu.rsrc    - 'clut' resource
  21.     *.cc            - SOURCE
  22.     view_3d.cc        - the 3D projector
  23.     window.h        \ my own private very simple MacApp: classlib for
  24.     SimpleWindow.cc / handling color Mac windows and offscreen GrafWorlds
  25.     *.PPM            - sample elevation maps (PPGM files) one can drop onto
  26.                       the 'Venus v3.5' application to fly through
  27.     The source code contains (too) many comments to show what
  28.     a particular piece of code does, as well as some tricks involved
  29.  
  30. Language: CodeWarrior C++ v11
  31. System: System 7.x; binaries are for a PowerMac
  32. Version: 3.5, May 1997
  33.  
  34. Note: Some ancillary code is provided in a binary form (as compiled libraries)
  35.       for compactness. The corresponding source code can be grabbed from
  36.       the Info-Mac (/info-mac/dev/lib/gray-image-23-cpp.hqx,
  37.                       /info-mac/dev/src/my-menv-notify-c.hqx) or
  38.       http://pobox.com/~oleg/ftp/packages/grayimage.cpt.hqx
  39.       http://pobox.com/~oleg/ftp/packages/mymenv-notify.cpt.hqx
  40.       http://pobox.com/~oleg/ftp/packages/c++advio.cpt.hqx
  41.       See http://pobox.com/~oleg/ftp/
  42.       for  more details.
  43. Comments-to: oleg@pobox.com
  44. Many-Thanks-To: Tim Clarke, tjc1005@hermes.cam.ac.uk (for inspiration)
  45.  
  46. Explanation:
  47.  
  48.     Just fire it up, sit back and enjoy. Hope you'll get some
  49. feeling that you're hovering over, or flying through the clouds. If you
  50. quit the program and start it over again, you'll get different clouds
  51. (which might be much better and more interesting to fly in).
  52.  
  53.     If you want to take a more active role, hold the mouse button down while
  54. moving the mouse. Your flight then is in your own hand (the one that holds the mouse).
  55. You have to keep the mouse button down all the time to hold onto control: when the
  56. mouse button is up, the thing flies by itself. You can also use the keyboard: arrows
  57. left/right/up/down move you around, PgUp/PgDn changes your altitude (or height of the
  58. horizon if pressed with the "Option"); try also 'z'/'Z' for zooming in/out. All other
  59. keys quietly kill the program (you can also quit by clicking a close box of the window).
  60.  
  61.     After you're done flying in a small window, click on a "zoom out" box.
  62. Yes, it does what you might expect it to, but you still may be up for some
  63. surprise... The mouse-control works here too!
  64.  
  65.     The Venus window is not only draggable and zoomable, it is now fully resizable.
  66. Just click on the lower right corner of the window (where the resize box usually is:
  67. the box will show up when you click there). You can then resize the window as usual.
  68.  
  69.     Tip! Screen updates will be _much_ faster if your monitor is set to 256 colors
  70. (that is, an indexed color, depth 8). The program won't die (let alone crash) at
  71. other settings: still, when the code detects an 8-bit indexed-color monitor, it has
  72. QuickDraw draw immensely faster. I  probably can make the thing blit just as fast
  73. on direct color (that is, 24-bit color) graphic devices, but I don't have one
  74. around.... Sorry...
  75.  
  76.     Venus can fly through _any_ cloud image that you "drop" onto it. The image must be
  77. in a PGM format ('PPGM' type, as assigned by the GraphicConverter). The image dimensions
  78. don't matter: the program would cut and fill in as necessary (assuming that the
  79. given map is periodic).The image file may contain a custom colormap: the code would
  80. try to load the first 'clut' resource it finds; if this clut is appropriate (contains
  81. 256 entries) it will be used to color the 3D view. See the comments to "ElevationMap.cc"
  82. for more details and justification. The distribution contains a few sample maps you
  83. can drop onto the Venus.
  84.  
  85.     Venus is now scriptable! Well, at the moment is supports only absolutely mandatory
  86. core events: Quit, OpenApplication (which is quietly ignored) and OpenDocument (which
  87. is used to handle dropped PPGM files). Still, it's a beginning...
  88.  
  89.     The application sports a nifty "custom" event queue that lets one "unget" an event,
  90. or push a new event into. The events pushed can be regular events, or "my events"
  91. (with eventKind = mykind), which are used to pass around requests for zooming, resizing,
  92. loading of the map, etc. Note for example, how resizing results in re-creation of a window.
  93. Once the code detects that the resize button was clicked, the code tracks the mouse, notes
  94. the new window dimensions, _closes_ the current window, changes the WIND template,
  95. but doesn't bother opening a new window: the code merely places an order to be fulfilled
  96. by the code that created the window the first time around. The custom event queue is also
  97. used by AEEvent handlers to place an "orders" to the main event loop. This structure
  98. (of a single dispatcher and multiple event producers and consumers) makes for a rather
  99. efficient and flexible system, with maximal code reuse, and as few global dependencies
  100. (global variables) as possible.
  101.  
  102.     This program is inspired by MARS.EXE  and its description
  103. posted in rec.games.programmer. There, the author of Mars, Tim Clarke,
  104. explained its guts, though he didn't give detailed equations and there
  105. were a few typos in his post. Source file view_3d.cc in the
  106. present submission contains the fullest description (I could come up
  107. with) of a 3D rendering technique used _here_: with background, equations,
  108. pseudocode and the actual code (and tricks with the fixed-point
  109. arithmetics: hey, no floating-point numbers are in here). I have to mention
  110. that in the present form, the rendering engine in Venus v3 has nothing to
  111. do with that of Tim Clarke's...
  112.  
  113.     If you need further information or details, please mail me, oleg@pobox.com
  114.     
  115. New in this version of Venus (version 3.5)
  116.     
  117. - New custom icons, many thanks to Teddy Schatz (BIadeRunr@aol.com)
  118. - The Venus window is not only draggable and zoomable, it is now fully resizable.
  119. - mouse control is back! As long as you hold the mouse button down, you control
  120.   where you go (where the clouds flow, that is). Also works in the full-screen mode!
  121. - The elevation map can be now loaded from a dropped 'PPGM' file; if the file has
  122.   a compatible clut, it will be loaded too.
  123. - Venus supports now the absolutely mandatory core suite of AppleEvents (Quit,
  124.   OpenApplication, OpenDocument)
  125. - Custom event queue (with an ability to unget an event, or push new events into the queue) 
  126.  
  127.  
  128. New in version 3.0
  129.  
  130. - A 3D rendering engine is inherited from Venus v2 (circling-in-clouds), still Venus v3
  131.   looks like Venus v1 (that is, flying-_through_-clouds)
  132.   The engine's abilities to do turns and twists aren't utilized yet
  133. - Arbitrary dimensions of a view window
  134. - New keys (added z/Z for zooming in/out, added changing of both the elevation and
  135.   the horizon)
  136. - New ways of doing animation (without relying on null events), although it is
  137.   a null event that triggers it...
  138. - Mind boggling (but more flexible) animation classes using templates;
  139.   more reliance on caches and more cutting corners: when objects are far away,
  140.   we don't have to actually project every darn point...
  141.   we can skip the points and/or decrease the depth at a faster rate...
  142. - Faster drawing: we try to do everything to make CopyBits work at the top of its speed:
  143.   if the program finds out that QD drawing can be optimized, it will:
  144.   if an off-screen GWorld and screen's GDevice found "compatible", CopyBits will be
  145.   heavily hinted at it right away. In favorable circumstances, screen updates are
  146.   probably as fast as one can make them using only standard system tools.
  147.   When drawing on the full screen, we cut the corners a bit: since our window is the
  148.   only one on screen, we can load all the colors we need directly into the GDevice,
  149.   not giving a darn for the other windows... We use ColorManager's function
  150.   RestoreEntries() for that purpose; btw, the third argument of this function, ReqListRec
  151.   isn't explained too much in IM (say, when IM said "size" one had to read "the number of
  152.   elements"; when it said "offset" it really meant "index"). So I had to do a bit of
  153.   disassembling and tracing through a few system calls...
  154.  
  155.  
  156. Yet to do
  157.  
  158.  - Overlay a 2D image of clouds on the top of the 3D picture
  159.  - Better hiding of a menu bar
  160.  - Make it scriptable: respond to start/stop animation, allow querying and setting
  161.    of projection, position, etc. parameters via AppleEvents
  162.  - Allow saving of the contents of the current window (as a PICT?): via cut,
  163.    drag, or in response to an AppleEvent command...
  164.  - A more advanced "flying" plan with twists and turns and tumbles...
  165.  - Sound?....
  166.  - The color map definitely needs an artistic touch... help will be very appreciated!
  167.